Monster Media 1996 #15

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / prog_gen / freeli10.zip / FREELIB.DOC < prev next >

Wrap

Text File | 1996-04-22 | 50KB | 1,698 lines

---------------------------------------------------------------------- ------------ FREELIB: The FREE Assembly Language Library ------------- --------------- Copyright (C) April 1996 Tenie Remmel ---------------- ---------------------------------------------------------------------- 1. Introduction ................................ Line 15 2. Terms of use/Legal disclaimer ............... Line 34 3. Processors, calling conventions ............. Line 55 4. Re-assembling ............................... Line 91 5. Program Syntax .............................. Line 116 6. Procedure Reference ......................... Line 176 7. Future additions, bug reporting ............. Line 1652 1. Introduction. FREELIB is a library of 130 procedures that may be useful for programming in assembly language. As the name implies, this is public domain, completely free for all non-commercial use. If you find this library useful, you are strongly encouraged to contribute some of your own routines for possible addition to FREELIB. Full source code is included, so if you find any bugs (!) or wish to make changes to any of the routines, you can. However, if you do make any improvements, please notify the author, so that FREELIB can continue to be expanded and improved. If you modify any part of this library, you may not distribute it, for free or not, without prior permission from the author (see below). Be sure to read the sections 2, 3 and 5 carefully, including the miscellaneous notes in section 3. 2. Terms of use/Legal disclaimer. This software is hereby released into the public domain, and may therefore be freely copied and distributed within the following restrictions: 1). It is distributed in its original, unmodified form, including all source code and documentation. 2). No fee is charged for use, copying or distribution. 3). The program may not be included with other goods or services supplied for a fee, unless specific written permission to do so is obtained in advance from the author. (E-mail: tjr19@mail.nwlink.com) This program is provided AS-IS without any warranty, express or implied, including but not limited to warranty of fitness for a particular purpose. 3. Processors, calling conventions, string type, etc. FREELIB is programmed in 80186 assembly language. This is to ensure compatibility with as many computers as possible, but not sacrificing very much speed. FREELIB uses the Pascal calling convention. The parameters are pushed on the stack in order, and the calling procedure does not have to worry about stack cleanup. This seems to be the fastest method, and it also helps in debugging... if the wrong number of arguments are pushed to call a procedure, the program will crash, which is much more obvious than the weird results produced with the 'C' convention, etc. Notice that in the source code, the syntax is given by a 'C' style prototype. Why a 'C' prototype? Well, Pascal does not have prototypes, and the 'C' prototype is useful to concisely show the syntax of a procedure on one line. Misc. Notes: Many of the routines assume DS = CS, so make sure that this is the case. The program is intended to be a .COM file, but .EXE files are possible as long as the DS = CS restriction is met. Do not use uninitialized data, it will confuse the memory manager. Use dynamically allocated memory instead. The fixed-point numbers are 16:16, and signed. The strings are ASCIIZ (null-terminated) strings, like in C. The long integers can be either signed or unsigned, depending on which multiply, divide and shift you use. When clock timings are given, they always include the call/return, and exclude the argument pushes. Even though some procedures require a character argument, a word-sized value must still be pushed. There is no way to push a byte value. The files TEXT???.INC are not to be included in your programs. They are internally used by the High-Res Text Mode routines in FREELIB3.ASX. The colorset in High-Res Text Mode is different, see below. Colorset in High-Res Text Mode: 0 = Black 8 = Dark Gray 1 = Dark Green 9 = Red 2 = Green 10 = Orange 3 = Light Green 11 = Yellow 4 = True Blue 12 = Sky Blue 5 = Dark Purple 13 = Dark Blue 6 = Magenta 14 = Cyan 7 = Light Gray 15 = White 4. Re-assembling FREELIB. A batch file (REDO.BAT) is provided for this purpose. These source files are .ASX files (ASsembly eXtended) which contain multiple modules. A utility (SPLIT.COM) is included to split the .ASX files. SPLIT.C is the 'C' source to SPLIT.COM. The batch file takes care of splitting the files. However, if you wish to add a new .ASX file (in addition to FREELIB1-3), you must modify the batch file, otherwise it will be ignored. SPLIT outputs TLIB command file codes. SPLIT takes zero or one arguments. When run with no arguments, it produces codes that end the command file. When run with an argument (what it is doesn't matter) it produces codes that continue to the next file. In the .ASX files, a line starting with three tildes (~) that are followed by a file name without extension will denote the beginning of a new module. Either make sure that all of the module names start with 'C_' or modify the REDO.BAT file. If you put any .ASM files with names starting with 'C_' in the FREELIB directory, be warned: they will be deleted along with the temporary .ASM files created by SPLIT. 5. Program syntax for use with FREELIB. Your program should do a near call, or jump, to the 'startup' procedure at the beginning. The main body of the program must be in the procedure 'main', which must be declared public. On entry to main, the number of arguments is in CX and a list of near pointers to the arguments is at offset DI. DS and ES both equal CS. AX, BX, DX, SI, and BP are undefined. You must declare as external all procedures that you intend to use. One way to simplify this is with a macro: ;************************************** Macro lcall prced ;; library call extrn prced:near ;; declare as external call prced ;; call procedure EndM ;************************************** and then you would replace 'call' with 'lcall' when calling library procedures. This is a skeleton program: ;************************************** Ideal ; ideal mode Public main ; declare main as public Extrn startup:near ; declare startup procedure Macro lcall prced ;; library call extrn prced:near ;; declare as external call prced ;; call procedure EndM Model Tiny ; tiny model CodeSeg ; code segment Org 100h ; .COM file start Start: jmp startup ; start up program Proc main ; main procedure ret ; return EndP main End Start ; entry at 'Start' ;************************************** 6. Reference: Syntax and description of all FREELIB procedures. ------------------------------------------------------------- ------------ Initialization and Exit Procedures ------------- ------------------------------------------------------------- ---------- startup Start program jmp startup This procedure must be jumped to at the beginning of your program. (See Section 5.) This procedure calls 'main'. It also does internal initialization, and sets null Ctrl-C and divide-error handlers. ---------- exit Exit program push retcode call exit This procedure exits your program with a return code. If exit is not used, the return code is the value of AX on return from main. ------------------------------------------------------------- ---------------------- File Procedures ---------------------- ------------------------------------------------------------- ---------- fopen Open file push offset filename push filemode call fopen ; AX = handle This procedure opens a buffered file. The handle is returned in AX. This handle is NOT a DOS handle. If it is used as such, the results are unpredictable. The file modes are: 0 Open for Read-Only (open if it exists, fail if not) 1 Modify for Read/Write (open if it exists, create if not) 2 Open for Read/Write (open if it exists, fail if not) 3 Create for Read/Write (truncate if it exists, create if not) ---------- fclose Close file push handle call fclose This procedure closes a buffered file. ---------- fgetc Get char from file push handle call fgetc ; AX = char This procedure gets a character from a buffered file. If the end of file is reached or an error occurs, -1 is returned. ---------- fputc Put char to file push handle push char call fputc ; AX = return code This procedure puts a character to a buffered file. If the end of file is reached or an error occurs, -1 is returned, otherwise the character is returned. ---------- fread Read block from file push handle push size push offset buf call fread ; AX = return code This procedure reads a block from a buffered file. The number of characters read is returned. If this is less than the requested size, the end of file was reached or an error occured. ---------- fwrite Write block to file push handle push size push offset buf call fwrite ; AX = return code This procedure writes a block to a buffered file. The number of characters written is returned. If this is less than the requested size, an error occured. ---------- fseek Set file pointer push handle push pos_hi push pos_lo push mode call fseek ; AX = return code This procedure sets the position of the file pointer. The position is a long integer. If an error occurs, 0 is returned, otherwise a nonzero value is returned. The seek modes are: 0 Seek from beginning of file 1 Seek from current position 2 Seek from end of file ---------- ftell Get file pointer push handle call ftell ; DX:AX = file pointer This procedure returns the position of the file pointer. ---------- fsetbuf Set file buffer size push size call fsetbuf This procedure sets the file buffer size. It does not affect currently open files. It only affects files that are opened after this call. The default size is 512 bytes, but it may be set to from 128 to 32752 bytes. If the size requested is greater than 32768, the high bit is simply masked off, f.i. 33024 will produce 256. ---------- ftrunc Truncate file push handle call ftrunc ; AX = return code This procedure truncates a buffered file at the current position. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ---------- fdel Delete file push offset filename call fdel ; AX = return code This procedure deletes a file. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ---------- fmove Move/Rename file push offset oldname push offset newname call fmove ; AX = return code This procedure moves and/or renames a file. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ------------------------------------------------------------- --------------- Directory and Disk Procedures --------------- ------------------------------------------------------------- ---------- mkdir Create Directory push offset dirname call mkdir ; AX = return code This procedure creates a directory. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ---------- rmdir Remove Directory push offset dirname call rmdir ; AX = return code This procedure deletes a directory. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ---------- setdir Set Current Directory push offset dirname call setdir ; AX = return code This procedure sets the current directory. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ---------- getdir Get Current Directory push offset buffer call getdir This procedure returns the current directory. The full path is returned in 'buffer'. ---------- setdrive Set Current Drive push dr_num call setdrive This procedure sets the current drive. The numbers are the same as the DOS drive numbers. (0 = default, 1 = A, 2 = B, 3 = C, etc.) ---------- getdrive Get Current Drive call getdrive ; AX = drive number This procedure returns the current drive. The numbers are the same as the DOS drive numbers. (0 = default, 1 = A, 2 = B, 3 = C, etc.) ---------- getdfree Get Free Disk Space push dr_num call getdfree ; DX:AX = amount of free space This procedure returns the amount of free disk space on a drive. The number returned is in bytes. ------------------------------------------------------------- ----------------- Memory Manager Procedures ----------------- ------------------------------------------------------------- ---------- allocmem Allocate Memory push size call allocmem ; AX = pointer This procedure allocates memory. If there was not a big enough block of memory, -1 is returned, otherwise a pointer to the block of memory is returned. ---------- freemem Free Memory push ptr call freemem This procedure frees memory. If 'ptr' does not point to a valid block, nothing happens. If free blocks abut the block to be freed, they are coalesced. ---------- getmfree Get Free Memory call getmfree ; AX = size of largest free block This procedure returns the size of the largest free block of memory. If there are no free blocks, 0 is returned. ---------- faralloc Allocate Far Memory push size call faralloc ; AX = segment This procedure allocates far memory. If there was not a big enough block of memory, -1 is returned, otherwise the segment of the memory block is returned. The size must be specified in paragraphs (16 bytes each). This calls the DOS allocate memory service. ---------- farfree Free Far Memory push seg call freemem This procedure frees far memory. If 'seg' is not the segment of a valid memory block, the results will be undefined. If free blocks abut the block to be freed, they are coalesced. This calls the DOS free memory service. ---------- getfarfree Get Free Far Memory call getfarfree ; AX = size of largest free block This procedure returns the size of the largest free block of far memory. If there are no free blocks, 0 is returned. ------------------------------------------------------------- ----------------- Put/Get String Procedures ----------------- ------------------------------------------------------------- ---------- puts Put String push offset string call puts This procedure writes a string to the screen. If the STDOUT handle is redirected, this still works. The string is output literally, using Int 29h. ---------- fputs Put String to File push handle push offset string call fputs This procedure writes a string to a file. If an error occurs, -1 is returned, otherwise a nonzero value is returned. The handle is a FREELIB handle, not a DOS handle. ---------- xputs Put String, Generalized push offset outfunc push offset string call xputs This procedure outputs a string using a user-defined function. The function must take one word argument, the character to output, save all registers, and return with a 'Ret 2' to clean up the stack. ---------- gets Get String push offset buffer push max call gets This procedure inputs a string from the keyboard. The string of maximum 'max' chars will be put into 'buffer'. Any excess characters will be discarded. This procedure allows simple editing using the <BkSp> key. ---------- fgets Get String from File push handle push offset buffer push max call fgets This procedure reads a line from a file. The string of maximum 'max' chars will be read into 'buffer'. The line must end with a CR/LF pair. An entire line will be input even if it exceeds 'max' characters. Any excess will be discarded. The handle is a FREELIB handle, not a DOS handle. ---------- xgets Get String, Generalized push offset outfunc push offset buffer push max push terminator call xgets This procedure reads a logical line using a user-defined function. The function must take zero arguments and return in AL the character input. No register except AX may be changed. The value 'terminator' must be returned on end of logical line. The string of maximum 'max' chars will be read into 'buffer'. An entire logical line will be input even if it exceeds 'max' characters. Any excess will be discarded. ------------------------------------------------------------- ------------- Formatted String Print Procedures ------------- ------------------------------------------------------------- ---------- printf Print Formatted String push offset fmtstr push offset arglist call printf This procedure prints a formatted string to the screen. It is similar to the 'printf()' in 'C'. In the format string, the '%' character is special. The '%' character can be followed by the following characters, which indicate what type of argument to print: %d Integer %x Hex integer %s String %c Character %ld Long integer %lx Long hex integer The parameter 'arglist' is a list of arguments, in order. Their types are taken from the format string. If the wrong type is specified in the format string, printf has no way of knowing, so the results will be unpredictable. Example of using printf: ;************************************** ... FmtStr db '%d %s %c %lx',0 ArgList dw 15600 db 'This is a string',0 db 'X' dd 1A2B3C4Dh ... push offset FmtStr push offset ArgList call printf ... ;************************************** This example will output '15600 This is a string X 1A2B3C4D'. ---------- fprintf Print Formatted String to File push handle push offset fmtstr push offset arglist call printf This procedure prints a formatted string to a file. It works the same way printf does. See 'printf' for more information. ---------- sprintf Print Formatted String to String push offset dest_str push offset fmtstr push offset arglist call printf This procedure prints a formatted string to a string. The string output will be null terminated. This procedure works the same way printf does. See 'printf' for more information. ---------- xprintf Print Formatted String, Generalized push offset outfunc push offset fmtstr push offset arglist call printf This procedure prints a formatted string using a user defined function. The function must take one word argument, the character to output, save all registers, and return with a 'Ret 2' to clean up the stack. This procedure works the same way printf does. See 'printf' for more information. ------------------------------------------------------------- ------------ Alphanumeric Conversion Procedures ------------- ------------------------------------------------------------- ---------- atoi Convert String to Integer push offset string call atoi ; AX = result This procedure converts a string to an integer. It recognizes the '-' and '+' signs, but it will stop on any other non-digit. The integer corresponding to the string is returned. If the result overflows, the low 16 bits of the result are returned. ---------- atol Convert String to Long push offset string call atol ; DX:AX = result This procedure converts a string to a long integer. It recognizes the '-' and '+' signs, but it will stop on any other non-digit. The long integer corresponding to the string is returned. If the result overflows, the low 32 bits of the result are returned. ---------- itoa Convert Integer to String push number push offset buffer call itoa This procedure converts an integer to a string. On return, 'buffer' will contain the decimal representation of 'number'. The string will be null terminated. If the number is negative, this will be handled correctly. ---------- ltoa Convert Long to String push num_hi push num_lo push offset buffer call ltoa This procedure converts a long integer to a string. On return, 'buffer' will contain the decimal representation of the number. The string will be null terminated. If the number is negative, this will be handled correctly. ---------- atofix Convert String to Fixed-Point push offset string call atofix ; DX:AX = result This procedure converts a string to a fixed-point number. Itrecognizes the '-' and '+' signs and the decimal point, but it will stop on any other non-digit. The fixed-point number corresponding to the string is returned. If the result overflows, the value returned will have the correct fractional part, and the integer part will be the low 16 bits of the true value. ---------- fixtoa Convert Fixed-Point to String push num_hi push num_lo push offset buffer call fixtoa This procedure converts a fixed-point number to a string. On return, 'buffer' will contain the decimal representation of the number. The string will be null terminated. If the number is negative, this will be handled correctly. Fractions will also be handled correctly. ------------------------------------------------------------- ------ Long Integer/Fixed Point Arithmetic Procedures ------- ------------------------------------------------------------- ---------- ldiv Long Divide push num1_hi push num1_lo push num2_hi push num2_lo call ldiv ; DX:AX = result This procedure divides unsigned long integers. It divides 'num1' by 'num2'. ---------- lidiv Long Divide, Signed push num1_hi push num1_lo push num2_hi push num2_lo call lidiv ; DX:AX = result This procedure divides signed long integers. It divides 'num1' by 'num2'. ---------- lmul Long Multiply push num1_hi push num1_lo push num2_hi push num2_lo call lmul ; DX:AX = result This procedure multiplies unsigned long integers. It takes 70 clock ticks on a 486, including the call/return but not the argument pushes. ---------- limul Long Multiply, Signed push num1_hi push num1_lo push num2_hi push num2_lo call limul ; DX:AX = result This procedure multiplies signed long integers. It takes 89-97 clock ticks on a 486, including the call/return but not the argument pushes. ---------- lshl Long Shift Left push num_hi push num_lo push dist call lshl ; DX:AX = result This procedure shifts a long integer to the left. It shifts 'num' by 'dist', and takes 37 clock ticks on a 486, including the call/return but not the argument pushes. ---------- lshr Long Shift Right push num_hi push num_lo push dist call lshr ; DX:AX = result This procedure shifts an unsigned long integer to the right. It shifts 'num' by 'dist', and takes 37 clock ticks on a 486, including the call/return but not the argument pushes. ---------- lsar Long Shift Right, Signed push num_hi push num_lo push dist call lsar ; DX:AX = result This procedure shifts a signed long integer to the right. It shifts 'num' by 'dist', and takes 39 clock ticks on a 486, including the call/return but not the argument pushes. ---------- fixmul Fixed-Point Multiply push num1_hi push num1_lo push num2_hi push num2_lo call fixmul ; DX:AX = result This procedure multiplies fixed-point numbers. It takes 101-109 clock ticks on a 486, including the call/return but not the argument pushes. ---------- fixdiv Fixed-Point Divide push num1_hi push num1_lo push num2_hi push num2_lo call fixdiv ; DX:AX = result This procedure divides fixed-point numbers. It divides 'num1' by 'num2'. ------------------------------------------------------------- ---------------------- String Procedures -------------------- ------------------------------------------------------------- ---------- strlen String Length push offset string call strlen ; AX = length This procedure returns the length of a string, not including the null terminator. ---------- strcpy Copy String push offset dest_str push offset src_str call strcpy This procedure copies 'src_str' to 'dest_str', including the null terminator. There is no checking to see if the string fits, so be careful. ---------- strcat Concatenate Strings push offset dest_str push offset src_str call strcat This procedure concatenates 'src_str' onto 'dest_str', including the null terminator. There is no checking to see if the string fits, so be careful. ---------- strcmp Compare Strings push offset string1 push offset string2 call strcmp ; AX = return value This procedure compares 'string1' and 'string2'. If 'string2' is lexicographically greater, a negative value is returned. If 'string1' is greater, a positive value is returned. If they are equal, zero is returned. ---------- stricmp Compare Strings, Case Insensitive push offset string1 push offset string2 call stricmp ; AX = return value This procedure compares 'string1' and 'string2'. If 'string2' is lexicographically greater, a negative value is returned. If 'string1' is greater, a positive value is returned. If they are equal, zero is returned. This procedure differs from strcmp in that the compare is case insensitive. ---------- strchr Search String for Char push offset string push char call strchr ; AX = return value This procedure searches for 'char' in 'string'. If the character is not found, -1 is returned, otherwise the position of the character in the string is returned. ---------- strstr Search String for Substring push offset string push offset substr call strchr ; AX = return value This procedure searches for 'substr' in 'string'. If the substring is not found, -1 is returned, otherwise the position of the substring in the main string is returned. ---------- strlwr Convert String to Lowercase push offset string call strlwr This procedure converts a string to lowercase. Any character in the string that is already lowercase or that is not a letter will not be affected. ---------- strupr Convert String to Uppercase push offset string call strupr This procedure converts a string to uppercase. Any character in the string that is already uppercase or that is not a letter will not be affected. ---------- strltrim Trim Leading Spaces push offset string call strltrim This procedure trims leading spaces from a string. If there are no leading spaces, nothing happens. ---------- strrtrim Trim Trailing Spaces push offset string call strrtrim This procedure trims trailing spaces from a string. If there are no trailing spaces, nothing happens. ------------------------------------------------------------- ------------------ Memory Block Procedures ------------------ ------------------------------------------------------------- ---------- memcpy Copy Memory Block push dest_offset push src_offset push length call memcpy This procedure copies a block of memory from 'src_offset' to 'dest_offset'. The block is of length 'length'. This procedure will work correctly if the blocks overlap. ---------- memset Set Memory Block push memd_offset push length push byte call memset This procedure fills a block of memory of length 'length' at 'mem_offset' with 'byte'. ---------- memcmp Compare Memory Blocks push dest_offset push src_offset push length call memcmp ; AX = return code This procedure compares two blocks of memory at offsets 'src_offset' and 'dest_offset'. The blocks are of length 'length'. If they are equal, 1 is returned, otherwise 0 is returned. ---------- memchr Search Memory Block push mem_offset push length push byte call memchr This procedure searches a block of memory of length 'length' at 'src_offset' for 'byte'. If the byte is found, its position within the block is returned, otherwise -1 is returned. ------------------------------------------------------------- ---------------- Search and Sort Procedures ----------------- ------------------------------------------------------------- ---------- isearch Search Array of Integers push offset array push size push elem call isearch ; AX = return code This procedure searches an array of integers of size 'size' for 'elem'. This procedure assumes that the array is sorted. If the element is found, its position in the array is returned, otherwise -1 is returned. ---------- lsearch Search Array of Longs push offset array push size push elem_hi push elem_lo call lsearch ; AX = return code This procedure searches an array of long integers of size 'size' for 'elem'. This procedure assumes that the array is sorted. If the element is found, its position in the array is returned, otherwise -1 is returned. ---------- ssearch Search Array of Strings push offset array push size push offset elem call ssearch ; AX = return code This procedure searches an array of strings of size 'size' for 'elem'. This procedure assumes that the array is sorted. If the element is found, its position in the array is returned, otherwise -1 is returned. ---------- xsearch Search Array, Generalized push offset array push size push offset elem push offset cmpfunc call xsearch ; AX = return code This procedure searches an array of pointers of size 'size' for 'elem'. It assumes that the array is sorted. If the element is found, its position in the array is returned, otherwise -1 is returned. This procedure uses a user-defined function. The function must take two word-sized pointer arguments. It must return the result of the comparison in AX so that a negative value indicates less, a positive value indicates greater, and zero indicates equal, and it also should preserve all registers except for AX. ---------- isort Sort Array of Integers push offset array push size call isort This procedure sorts an array of integers of size 'size' in ascending order. ---------- lsort Sort Array of Longs push offset array push size call lsort This procedure sorts an array of long integers of size 'size' in ascending order. ---------- ssort Sort Array of Strings push offset array push size call ssort This procedure sorts an array of strings of size 'size' in alphabetical order. ---------- xsort Sort Array, Generalized push offset array push size push offset cmpfunc call xsort This procedure sorts an array of pointers of size 'size'. This is the generalized sort procedure. This procedure uses a user-defined function. The function must take two word-sized pointer arguments. It must return the result of the comparison in AX so that a negative value indicates less, a positive value indicates greater, and zero indicates equal, and it also should preserve all registers except for AX. ------------------------------------------------------------- ----------------- Miscellaneous Procedures ------------------ ------------------------------------------------------------- ---------- cputype Get CPU Type call cputype ; AX = CPU type This procedure returns the CPU type (0 = 8086, 1 = 186, etc.) It cannot detect SX/DX variations. ---------- fputype Get FPU Type call fputype ; AX = FPU type This procedure returns the FPU type (0 = 8087, 1 = 187, etc.) If there is no FPU, -1 is returned. ---------- atexit Register Exit Function push offset func call atexit This procedure registers a function for calling on exit. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ---------- bitcnt Count Bits push number call bitcnt ; AX = number of set bits This procedure returns the number of set bits in an integer. ---------- highbit Find High Bit push number call highbit ; AX = highest bit This procedure returns the positon of the highest set bit in an integer. -1 is returned if it is zero. ---------- sqrt Square Root push num_hi push num_lo call sqrt ; AX = result This procedure returns the square root of a long integer. The result is a normal integer. This procedure treats all values as unsigned. ---------- exec Execute Program push offset progname push offset cmdline call exec ; AX = return code This procedure executes another program as a child process, with arguments in 'cmdline'. If an error occurs, 0 is returned, otherwise a nonzero value is returned. ---------- rand Random Number push max call rand ; AX = result This procedure returns a random number below 'max'. ---------- srand Seed Random Numbers call srand This procedure seeds the random number generator with the system clock. ---------- delay Delay push delaytime call delay This procedure delays for a specified number of milliseconds before returning. ---------- sound Set Speaker push freq call sound This procedure turns on the speaker at a specified frequency. ---------- nosound Turn Speaker Off call nosound This procedure turns the speaker off. ------------------------------------------------------------- ----------- High-Res Text Mode (90x34) Procedures ----------- ------------------------------------------------------------- ---------- inittext Initialize Text System call inittext This procedure initializes the High-Res Text Mode. ---------- closetext Close Text System call closetext This procedure closes the High-Res Text system, and sets the standard text mode. ---------- clrscr Clear Screen call clrscr This procedure clears the screen on the current video page. ---------- setwin Set Window push x1 y1 push x2 y2 push rel_flag call setwin This procedure sets the clipping window. 'rel_flag' indicates whether coordinates will be relative to the window or not. ---------- clrwin Clear Window call clrwin This procedure clears the current window. ---------- setpage Set Video Page push page_num call setpage This procedure sets the current video page. The page number must be between 0 and 5 (there are six pages). ---------- getpage Get Video Page call getpage ; AX = current page This procedure returns the current video page. ---------- setcolor Set Color push color call setcolor This procedure sets the current text color. The color is a byte, 0XYh, where X is the background color and Y is the foreground color. ---------- getcolor Get Color call getcolor ; AX = current color This procedure returns the current text color. ---------- box Draw Box push x1 y1 push x2 y2 push char call box This procedure draws a box with character 'char'. The box is clipped to the current window. ---------- sbox Draw Style Box push x1 y1 push x2 y2 push style call sbox This procedure draws a style box. The box is clipped to the current window. Here is the list of styles: 0 Blank 1 Single Line 2 Double Line 3 Single/Double 4 Double/Single ---------- fbox Draw Filled Box push x1 y1 push x2 y2 push char call fbox This procedure draws a filled box with character 'char'. The box is clipped to the current window. ---------- hline Draw Horizontal Line push x1 x2 push y push char call hline This procedure draws a horizontal line with character 'char'. The line is clipped to the current window. ---------- vline Draw Vertical Line push y1 y2 push x push char call vline This procedure draws a vertical line with character 'char'. The line is clipped to the current window. ---------- hsline Draw Horizontal Style Line push x1 x2 push y push style call hsline This procedure draws a horizontal style line. The line is clipped to the current window. See the description for 'sbox' for a list of the styles. ---------- vsline Draw Vertical Style Line push y1 y2 push x push style call vsline This procedure draws a horizontal style line. The line is clipped to the current window. See the description for 'sbox' for a list of the styles. ---------- gotoxy Set Cursor Position push x y call gotoxy This procedure sets the position of the cursor. It is clipped to the current window. ---------- getx Get Cursor X call getx ; AX = current X position This procedure returns the X position of the cursor. If the window relative flag is set, the position will be relative to the current window. ---------- gety Get Cursor Y call gety ; AX = current Y position This procedure returns the Y position of the cursor. If the window relative flag is set, the position will be relative to the current window. ---------- setctype Set Cursor Type push cur_type call setctype This procedure sets the type of the cursor. The format is: 0XXYYh, where XX is the starting line (0-13) and YY is the ending line (0-13). ---------- getctype Get Cursor Type call getctype ; AX = cursor type This procedure returns the current cursor type. The format is: 0XXYYh, where XX is the starting line (0-13) and YY is the ending line (0-13). ---------- setch Set Character push x y push char call setch This procedure sets the character at (x, y) to 'char'. The output is clipped to the current window. ---------- setat Set Attribute push x y push attr call setat This procedure sets the attribute at (x, y) to 'attr'. The output is clipped to the current window. ---------- setcha Set Char & Attr. push x y push char push attr call setcha This procedure sets the character at (x, y) to 'char', and the attribute to 'attr'. The output is clipped to the current window. ---------- readcha Read Char & Attr. push x y call readcha ; AL = char, AH = attr This procedure returns the character and attribute at (x, y). ---------- tputs Put String at (X, Y) push x y push offset string call tputs This procedure prints 'string' at (x, y). Output is clipped to the current window. Output will not wrap around lines. Control characters will be displayed literally. ---------- tprintf Print Formatted String at (X, Y) push x y push offset fmtstr push offset arglist call tprintf This procedure prints a formatted string at (x, y). It is equivalent to a 'sprintf' followed by 'tputs'. See 'sprintf' and 'tputs' for more information. ---------- getline Get Line of Text push x y push offset buffer push min push max call getline This procedure inputs a line of text from the user. A field is drawn at (x, y) extending for (max - 1) characters, and the string is input there. Full editing, i.e. insert/delete, etc., is supported. A string of minimum 'min' and maximum (max - 1) characters will be put into 'buffer'. ---------- setglchar Set Char for 'getline' push char call setglchar This sets the character used to clear the input field in 'getline'. The default value is a space (20h). Another useful value is the small bullet (0FAh). ---------- gettext Get Block of Text push offset buffer push x1 y1 push x2 y2 call gettext This procedure captures a rectangular block of text into 'buffer'. No clipping is performed. ---------- puttext Put Block of Text push offset buffer push x1 y1 call puttext This procedure displays a rectangular block of text from 'buffer' at (x1, y1). Output is clipped to the current window. ---------- movetext Move Block of Text push x1 y1 push x2 y2 push x y call movetext This procedure moves a rectangular block of text from (x1, y1)-(x2, y2) to (x, y). If the blocks overlap, it will be handled correctly. No clipping is performed and the window relative flag is ignored. ---------- delline Delete Line push y call delline This procedure deletes a line (at 'y') from the current window. All text below the line is scrolled up, and the bottom line is cleared. ---------- insline Insert Line push y call insline This procedure inserts a line (at 'y') from the current window. All text below the line is scrolled down, and the inserted line is cleared. ---------- scroll Scroll Window push dir call scroll This procedure scrolls the current window. The values for the direction 'dir' are: 0 Scroll Up 1 Scroll Down 2 Scroll Left 3 Scroll Right ------------------------------------------------------------- -------- High-Res Text Mode (90x34) Mouse Procedures -------- ------------------------------------------------------------- ---------- minit Initialize Mouse System call minit ; AX = return code This procedure initializes the High-Res Text Mode Mouse Driver. If an error occurs or the mouse is not found, 0 is returned, otherwise a nonzero value is returned. ---------- mclose Close Mouse System call mclose This procedure closes the mouse system. ---------- mshow Show Mouse Cursor call mshow This procedure displays the mouse cursor on the screen. ---------- mhide Hide Mouse Cursor call mhide This procedure hides the mouse cursor. ---------- mget Get Mouse Position call mget ; AX = button status ; BX = mouse X position ; CX = mouse Y position This procedure returns the position and status of the mouse. The format for the button status is: Bit Meaning 0 Left button 1 Right button 2 Middle button ---------- mgetdn Get Mouse Presses push button call mgetdn ; AX = press count ; BX = X position at last press ; CX = Y position at last press This procedure returns the status of a particular mouse button, for presses. The button values are as follows: 0 Left button 1 Right button 2 Middle button ---------- mgetup Get Mouse Releases push button call mgetup ; AX = release count ; BX = X position at last release ; CX = Y position at last release This procedure returns the status of a particular mouse button, for releases. See 'mgetup' for button values. 7. Future additions, bug reporting, etc. Bugs may be reported to the author at: tjr19@mail.nwlink.com. In the future, a set of wrapper procedures for calling some of the FREELIB routines from 'C' may be provided. This is a list of the routines wanted for future addition: (1) VGA graphics. (16 AND 256 colors, hopefully integrated, i.e. they do both modes) (2) EMS/XMS/Disk virtual memory manager. Should be transparent as to which medium is being used. (3) Low-level disk routines (read/write sector, format floppy). (4) Indefinite long arithmetic, 256 bytes at least. (5) Routines to read and write configuration data from the program's executable file. (6) Inter-procedure jumps, like the 'C' setjmp() and longjmp(). (7) Sound card interface routines. (8) General data compression. (9) Process management and multitasking. (10) Anything else that might be useful!!! ---------------------------------------------------------------------- ----------------------------------------------------------------------